<!DOCTYPE html>
<html lang="en-US">
    <head>
        <title>Data::Diver - Simple, ad-hoc access to elements of deeply nested structures - metacpan.org</title>
        <link rel="preload" as="fetch" href="https://metacpan.org/account/login_status" crossorigin="anonymous" />
        <link href="https://metacpan.org/_assets/b8ccceeed47a0652049703d99326a9cea4933443.css" rel="stylesheet" type="text/css">
        <script src="https://metacpan.org/_assets/6bfedafe2d7caa915b7d84f61b45936818e3242e.js" type="text/javascript" defer></script>
        <link rel="alternate" type="application/rss+xml" title="Recent CPAN Uploads of Data-Diver - MetaCPAN" href="https://metacpan.org/dist/Data-Diver/releases.rss" />
        <link rel="canonical" href="./Data::Diver.html" />
        <meta name="description" content="Simple, ad-hoc access to elements of deeply nested structures" />
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">
        <link rel="shortcut icon" href="https://metacpan.org/static/icons/favicon.ico">
        <link rel="apple-touch-icon" sizes="152x152" href="https://metacpan.org/static/icons/apple-touch-icon.png">
        <link rel="search" href="https://metacpan.org/static/opensearch.xml" type="application/opensearchdescription+xml" title="MetaCPAN">
        <script>
          (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
          })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

          (function(skey, ga_id){
            ga('create', ga_id, {
              siteSpeedSampleRate : 100,
              storage             : 'none',
              clientId            : localStorage.getItem(skey)
            });
            ga(function(tracker) {
              localStorage.setItem(skey, tracker.get('clientId'));
            });
            ga('send', 'pageview');
          })('ga:clientId', 'UA-27829474-1');
        </script>
<meta name="twitter:card"        content="summary" />
<meta name="twitter:url"         content="https://metacpan.org/pod/Data::Diver" />
<meta name="twitter:title"       content="Data::Diver" />
<meta name="twitter:description" content="Simple, ad-hoc access to elements of deeply nested structures" />
<meta name="twitter:site"        content="metacpan" />
    </head>
    <body>
        <nav class="navbar navbar-default" role="navigation">
            <div class="header-logo-large hidden-xs">
              <a href="https://metacpan.org/" tabindex="0">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#logo" />
                </svg>
              </a>
            </div>
            <div class="header-logo-icon visible-xs">
              <a href="https://metacpan.org/">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#dots" />
                </svg>
              </a>
            </div>
            <ul class="nav navbar-nav menu-items hidden-xs hidden-sm">
              <li><a href="https://metacpan.org/about">About</a></li>
              <li><a href="https://metacpan.org/about/sponsors">Sponsor</a></li>
              <li><a href="https://grep.metacpan.org/">grep::cpan</a></li>
              <li><a href="https://metacpan.org/recent">Recent</a></li>
              <li><a href="https://metacpan.org/about/faq">FAQ</a></li>
              <li><a href="https://metacpan.org/tools">Tools</a></li>
              <li><a href="https://fastapi.metacpan.org/">API</a></li>
            </ul>
            <ul class="nav navbar-nav navbar-right">
                <button type="button" class="searchbar-btn visible-xs visible-sm">
                    <i class="fa fa-search button-fa-icon"></i>
                </button>
                <form action="https://metacpan.org/search" class="searchbar-form visible-md visible-lg search-form form-horizontal">
                   <input type="hidden" name="size" id="metacpan_search-size" value="20">
                  <div class="form-group">
                      <div class="search-group">
                        <i class="fa fa-search"></i>
                        <input type="text" name="q" placeholder="Search the CPAN" size="41" autocorrect="off" autocapitalize="off" spellcheck="false" id="metacpan_search-input" class="form-control" value="">
                      </div>
                  </div>
                </form>
                    <li class="icon-slidepanel visible-xs visible-sm">
                      <button data-toggle="slidepanel" data-target=".slidepanel">
                        <span class="button-fa-icon">
                          <i class="fa fa-bars slidepanel-open"></i>
                          <i class="fa fa-times slidepanel-close"></i>
                        </span>
                      </button>
                    </li>
                <form action="https://metacpan.org/account/logout" method="POST" id="metacpan-logout"></form>
                <li class="dropdown logged_in" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon logged-in-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li><a href="https://metacpan.org/account/identities">Identities</a></li>
                        <li><a href="https://metacpan.org/account/profile">Profile</a></li>
                        <li><a href="https://metacpan.org/account/favorite/list">Favorites</a></li>
                        <li>
                            <a href="./Data::Diver.html#" type="button" onclick="$('#metacpan-logout').submit(); return false">
                              Logout
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_out" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li>
                            <a href="https://metacpan.org/login/github">
                                <i class="fab fa-github fa-fw"></i>
                                GitHub
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/twitter">
                                <i class="fab fa-twitter fa-fw"></i>
                                Twitter
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/google">
                                <i class="fab fa-google fa-fw"></i>
                                Google
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_placeholder">
                    <button>
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                    </button>
                </li>
            </ul>
        </nav>
        <div class="page-content ">
          <!--
          <div class="top-notify-banner">
            <i class="fas fa-info-circle"></i>
          </div>
          -->
          <nav class="sidebar">
            <div class="slidepanel">
              <ul class="nav-list ">
    <li class="nav-header no-margin-top">
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The date that this version of Data-Diver was released.">
      <span class="relatize">03 Sep 2005 07:08:23 UTC</span>
    </li>
  <li>
    Distribution: <a href="https://metacpan.org/dist/Data-Diver">Data-Diver</a>
  </li>
  <li>
    Module version: 1.0101
  </li>
  <li>
    <a data-keyboard-shortcut="g s" href="https://metacpan.org/dist/Data-Diver/source/Diver.pm">Source</a>
    (<a href="https://metacpan.org/dist/Data-Diver/source/Diver.pm?raw=1">raw</a>)
  </li>
  <li>
    <a data-keyboard-shortcut="g b" href="https://metacpan.org/dist/Data-Diver/source">Browse</a>
    (<a href="https://metacpan.org/dist/Data-Diver/source?raw=1">raw</a>)
  </li>
    <li>
      <a data-keyboard-shortcut="g c" href="https://metacpan.org/dist/Data-Diver/changes">Changes</a>
    </li>
    <li>
      <a class="nopopup" href="https://metacpan.org/dist/Data-Diver/contribute">How to Contribute</a>
    </li>
    <li>
      <a rel="noopener nofollow" data-keyboard-shortcut="g i" href="https://rt.cpan.org/Public/Dist/Display.html?Name=Data-Diver">Issues</a>
      (6)
    </li>
    <li>
      <a rel="noopener nofollow" href="http://matrix.cpantesters.org/?dist=Data-Diver+1.0101" title="Matrix">Testers</a>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpants.cpanauthors.org/release/TYEMQ/Data-Diver-1.0101">Kwalitee</a>
    </li>
    <li>
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The # people with an indexing permission on Data-Diver who have released something to CPAN in the last 2 years (i.e. the # people likely able to release critical fixes in a timely manner)">
      Bus factor: 0
      </div>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpancover.com/latest/Data-Diver-1.0101/index.html">86.16% Coverage </a>
    </li>
    <li>
      License: unknown
    </li>
    <li class="nav-header">Activity</li>
    <li>
<div class="activity-graph">
    <img src="https://metacpan.org/dist/Data-Diver/activity.svg?res=month" />
    <div class="comment">24 month</div>
</div>
    </li>
    <li class="nav-header">Tools</li>
    <li>
      <a itemprop="downloadUrl" href="https://cpan.metacpan.org/authors/id/T/TY/TYEMQ/Data-Diver-1.0101.tgz">
      Download (<span itemprop="fileSize">7.44KB</span>)</a>
    </li>
    <li>
      <a href="https://explorer.metacpan.org/?url=%2Fmodule%2FTYEMQ%2FData-Diver-1.0101%2FDiver.pm">
        MetaCPAN Explorer
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Data-Diver/permissions">
        Permissions
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Data-Diver/releases.rss">
        Subscribe to distribution
      </a>
    </li>
    <li>
      <button class="btn btn-link" data-toggle="modal" data-target="#metacpan_install-instructions-dialog">
        Install Instructions
      </button>
    </li>
    <li>
      <form action="https://metacpan.org/search">
        <input type="hidden" name="q" value="dist:Data-Diver">
        <input type="search" name="q" placeholder="Search distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
      </form>
    </li>
    <li>
      <form action="https://grep.metacpan.org/search">
        <input type="hidden" name="qd" value="Data-Diver">
        <input type="hidden" name="source" value="metacpan">
        <input type="search" name="q" placeholder="grep distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
     </form>
    </li>
    <li class="version-jump">
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/Diver.pm&#39;" class="form-control tool-bar-form">
  <option disabled selected>Jump to version</option>
<option
  disabled
  value="TYEMQ/Data-Diver-1.0101"
>1.0101
  (TYEMQ on 2005-09-03)</option>
<option
  
  value="TYEMQ/Data-Diver-1.0002"
>1.0002
  (TYEMQ on 2005-07-26)</option>
</select>
    </li>
    <li class="version-diff">
<select onchange="document.location.href='/release/TYEMQ/Data-Diver-1.0101/diff/' + encodeURIComponent(this.value) + '/Diver.pm'
" class="form-control tool-bar-form">
  <option disabled selected>Diff with version</option>
<option
  disabled
  value="TYEMQ/Data-Diver-1.0101"
>1.0101
  (TYEMQ on 2005-09-03)</option>
<option
  
  value="TYEMQ/Data-Diver-1.0002"
>1.0002
  (TYEMQ on 2005-07-26)</option>
</select>
    </li>

    <li>
<ul class="dependencies">
  <li class="nav-header">Dependencies</li>
  <li><i class="ttip" title="dynamic_config enabled">unknown</i></li>
  <li>
    <hr>
  </li>
  <li>
    <a href="https://metacpan.org/module/Data::Diver/requires">Reverse dependencies</a>
  </li>
  <li>
    <a href="http://deps.cpantesters.org/?module=Data%3A%3ADiver">CPAN Testers List</a>
  </li>
  <li>
    <a href="https://cpandeps.grinnz.com/?dist=Data-Diver">Dependency graph</a>
  </li>
</ul>
    </li>
    <li class="nav-header">Permalinks</li>
    <li>
      <a href="https://metacpan.org/release/TYEMQ/Data-Diver-1.0101/view/Diver.pm">This version</a>
    </li>
    <li>
      <a href="./Data::Diver.html">Latest version</a>
    </li>
    <li>
<div class="plussers">
<div class="nav-header">++ed by:</div>
<div>
<a class="display-all" href="https://metacpan.org/author/TOSHIOITO"><img src="https://www.gravatar.com/avatar/8bf554984c177c27b2ebac9cf36303fc?d=identicon&amp;s=20" title="TOSHIOITO" alt="TOSHIOITO"></a>
<a class="display-all" href="https://metacpan.org/author/POTATOGIM"><img src="https://www.gravatar.com/avatar/82f1c6258702415af6e26187f1e36850?d=identicon&amp;s=20" title="POTATOGIM" alt="POTATOGIM"></a>
<a class="display-all" href="https://metacpan.org/author/DRAEGTUN"><img src="https://www.gravatar.com/avatar/6f1ae19bf6507a7bd1ea0d0f6abfeb01?d=identicon&amp;s=20" title="DRAEGTUN" alt="DRAEGTUN"></a>
<a class="display-all" href="https://metacpan.org/author/CHANKEY"><img src="https://www.gravatar.com/avatar/5e3dc77d6818da1eba913fe7f3fed8ce?d=identicon&amp;s=20" title="CHANKEY" alt="CHANKEY"></a>
</div>
<!-- Display counts of plussers-->
<div>
    <a href="https://metacpan.org/dist/Data-Diver/plussers">4 PAUSE users</a>
</div>
<div>
    4 non-PAUSE users
</div>
</div>
    </li>
    <li>
    </li>
              </ul>
            </div>
          </nav>
          <div class="content-navigation">
<div class="breadcrumbs">
  <span>
    <a data-keyboard-shortcut="g a" rel="author" href="https://metacpan.org/author/TYEMQ" class="author-name">Tye McQueen</a>
  </span>
  <span>&nbsp;/&nbsp;</span>
  <div class="release dist-release status-latest maturity-released">
    <span class="dropdown"><b class="caret"></b></span>
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/Diver.pm&#39;" class="">
<option
  selected
  value="TYEMQ/Data-Diver-1.0101"
>1.0101
  (TYEMQ on 2005-09-03)</option>
<option
  
  value="TYEMQ/Data-Diver-1.0002"
>1.0002
  (TYEMQ on 2005-07-26)</option>
</select>
    <a data-keyboard-shortcut="g d" class="release-name" href="https://metacpan.org/dist/Data-Diver">Data-Diver-1.0101</a>
  </div>
<span class="river-gauge-gauge">
  <svg width="24px"
       height="15px"
       version="1.1"
       xmlns="http://www.w3.org/2000/svg"
       xmlns:xlink="http://www.w3.org/1999/xlink">

    <g>
      <title>        River stage one &#10;
          • 8 direct dependents &#10;          • 8 total dependents
      </title>

      <rect x="0"  y="0" width="4" height="15" fill="#7ea3f2" />
      <rect x="5"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="10"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="15"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="20"  y="0" width="4" height="15" fill="#e4e2e2" />
    </g>
  </svg>

</span>
<div id="Data-Diver-fav" class="logged_in">
<form action="https://metacpan.org/account/favorite/add" style="display: inline" onsubmit="return favDistribution(this)">
    <input type="hidden" name="remove" value="0">
    <input type="hidden" name="release" value="Data-Diver-1.0101">
    <input type="hidden" name="author" value="TYEMQ">
    <input type="hidden" name="distribution" value="Data-Diver">
    <button type="submit" class="favorite highlight"><span>8</span> ++</button>
</form>
</div>
<div class="logged_out">
<a href="./Data::Diver.html" onclick="alert('Please sign in to add favorites'); return false" class="favorite highlight">
<span>8</span> ++</a>
</div>
   / <span>Data::Diver</span>
</div>
          </div>
          <main class="content">


<nav class="toc">
  <div class="toc-header"><strong>Contents</strong></div>
<ul>
  <li><a href="./Data::Diver.html#NAME">NAME</a></li>
  <li><a href="./Data::Diver.html#SUMMARY">SUMMARY</a></li>
  <li><a href="./Data::Diver.html#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="./Data::Diver.html#DESCRIPTION">DESCRIPTION</a>
    <ul>
      <li><a href="./Data::Diver.html#Dive">Dive</a></li>
      <li><a href="./Data::Diver.html#DiveVal">DiveVal</a></li>
      <li><a href="./Data::Diver.html#DiveRef">DiveRef</a></li>
      <li><a href="./Data::Diver.html#Simple-&#39;key&#39;-values">Simple &#39;key&#39; values</a></li>
      <li><a href="./Data::Diver.html#DiveError">DiveError</a></li>
      <li><a href="./Data::Diver.html#DiveClear">DiveClear</a></li>
      <li><a href="./Data::Diver.html#DiveDie">DiveDie</a></li>
      <li><a href="./Data::Diver.html#Advanced-&#39;key&#39;-values">Advanced &#39;key&#39; values</a></li>
    </ul>
  </li>
  <li><a href="./Data::Diver.html#AUTHOR">AUTHOR</a></li>
  <li><a href="./Data::Diver.html#SEE-ALSO">SEE ALSO</a></li>
</ul></nav>
<div class="pod anchors">
<h1 id="NAME">NAME</h1>

<p>Data::Diver - Simple, ad-hoc access to elements of deeply nested structures</p>

<h1 id="SUMMARY">SUMMARY</h1>

<p>Data::Diver provides the Dive() and DiveVal() functions for ad-hoc access to elements of deeply nested data structures, and the DiveRef(), DiveError(), DiveClear(), and DiveDie() support functions.</p>

<h1 id="SYNOPSIS">SYNOPSIS</h1>

<pre><code>    use Data::Diver qw( Dive DiveRef DiveError );

    my $root= {
        top =&gt; [
            {   first =&gt; 1 },
            {   second =&gt; {
                    key =&gt; [
                        0, 1, 2, {
                            three =&gt; {
                                exists =&gt; &#39;yes&#39;,
                            },
                        },
                    ],
                },
            },
        ],
    };

    # Sets $value to &#39;yes&#39;
    # ( $root-&gt;{top}[1]{second}{key}[3]{three}{exists} ):
    my $value= Dive( $root, qw( top 1 second key 3 three exists ) );

    # Sets $value to undef() because &quot;missing&quot; doesn&#39;t exist:
    $value= Dive( $root, qw( top 1 second key 3 three missing ) );

    # Sets $value to undef() because
    # $root-&gt;{top}[1]{second}{key}[4] is off the end of the array:
    $value= Dive( $root, qw( top 1 second key 4 ... ) );

    # Sets $value to undef() because
    # $root-&gt;{top}[1]{second}{key}[-5] would be a fatal error:
    $value= Dive( $root, qw( top 1 second key -5 ... ) );

    # Sets $ref to \$root-&gt;{top}[9]{new}{sub} (which grows
    # @{ $root-&gt;{top} } and autovifies two anonymous hashes):
    my $ref= DiveRef( $root, qw( top 9 new sub ) );

    # die()s because &quot;other&quot; isn&#39;t a valid number:
    $ref= DiveRef( $root, qw( top other ... ) );

    # Does: $root-&gt;{num}{1}{2}= 3;
    # (Autovivifies hashes despite the numeric keys.)
    DiveVal( $root, \( qw( num 1 2 ) ) ) = 3;
    # Same thing:
    ${ DiveRef( $root, &#39;num&#39;, \1, \2 ) } = 3;

    # Retrieves above value, $value= 3:
    $value= DiveVal( $root, &#39;num&#39;, \1, \2 );
    # Same thing:
    $value= ${ DiveRef( $root,  \( qw( num 1 2 ) ) ) };

    # Tries to do $root-&gt;{top}{1} and dies
    # because $root-&gt;{top} is an array reference:
    DiveRef( $root, &#39;top&#39;, \1 );

    # To only autovivify at the last step:
    $ref= DiveRef(
        Dive( $root, qw( top 1 second key 3 three ) ),
        &#39;missing&#39; );
    if(  $ref  ) {
        $$ref= &#39;me too&#39;
    } else {
        my( $nestedRef, $svKey, $errDesc )= DiveError();
        die &quot;Couldn&#39;t dereference $nestedRef via $$svKey: $errDesc\n&quot;;
    }</code></pre>

<h1 id="DESCRIPTION">DESCRIPTION</h1>

<p>Note that Data::Diver does <code>use strict;</code> and so will not use symbolic references. That is, a simple string can never be used as a reference.</p>

<h2 id="Dive">Dive</h2>

<pre><code>    $value= Dive( $root, @ListOfKeys )</code></pre>

<p>Dive() pulls out one value from a nested data structure.</p>

<p>Dive() absolutely refuses to autovivify anything. If you give any &#39;key&#39; that would require autovivification [or would cause an error or warning], then an empty list is returned.</p>

<p>How Dive() works is easiest to &quot;explain&quot; by looking at the examples listed in the <a href="./Data::Diver.html#SYNOPSIS">&quot;SYNOPSIS&quot;</a> section above.</p>

<p>$root should be a reference, usually a reference to hash or to an array. @ListOfKeys should be a list of values to use as hash keys or array indices [or a few other things] that will be used to deference deeper and deeper into the data structure that $root refers to.</p>

<p>More details can be found under <a href="./Data::Diver.html#Simple-&#39;key&#39;-values">&quot;Simple &#39;key&#39; values&quot;</a> and <a href="./Data::Diver.html#Advanced-&#39;key&#39;-values">&quot;Advanced &#39;key&#39; values&quot;</a> further down.</p>

<p>If you want to distinguish between <code>exists</code> and <code>defined</code> for a hash element, then you can distinguish between an empty list, <code>( )</code>, being returned and one <code>undef</code>, <code>( undef )</code>, being returned:</p>

<pre><code>    my @exists= Dive( \%hashOfHashes, &#39;first&#39;, &#39;second&#39; );
    if(  ! @exists  ) {
        warn &quot;\$hashOfHashes{first}{second} does not exists.\n&quot;;
    } elsif(  ! defined $exists[0]  ) {
        warn &quot;\$hashOfHashes{first}{second} exists but is undefined.\n&quot;;
    }</code></pre>

<h2 id="DiveVal">DiveVal</h2>

<pre><code>    $val= DiveVal( $root, @ListOfKeys );

    DiveVal( $root, @ListOfKeys )= $val;</code></pre>

<p>DiveVal() is very much like Dive() except that it autovivifies if it can, dies if it can&#39;t, and is an LValue subroutine. So you can assign to DiveVal() and the dereferenced element will be modified. You can also take a reference to the call to DiveVal() or do anything else that you can do with a regular scalar variable.</p>

<p>If $root is undefined, then DiveVal() immediately returns <code>( undef )</code> [without overwriting <code>DiveError()</code>]. This is for the special case of using <code>DiveVal( Dive( ... ), ... )</code> because you want to only allow partial autovivifying.</p>

<h2 id="DiveRef">DiveRef</h2>

<pre><code>    $ref= DiveRef( $root, @ListOfKeys )</code></pre>

<h2 id="Simple-&#39;key&#39;-values"><a id="Simple"></a><a id="Simple--key--values"></a>Simple &#39;key&#39; values</h2>

<p>Both Dive() and DiveRef() start by trying to dereference $root using the first element of @ListOfKeys. We refer to the resulting value as <code>$ref</code> and, if there are more elements in @ListOfKeys, then the next step will be to try to dereference <code>$ref</code> using that next &#39;key&#39; [producing a new value for <code>$ref</code>].</p>

<p>To dereference an array reference, you must give a &#39;key&#39; value that is defined and matches <code>m/^-?\d+$/</code>. So, if you have more general numeric values, you should use <code>int()</code> to convert them to simple integers.</p>

<p>To dereference a hash reference, you must give a &#39;key&#39; value that is <code>defined</code> (or that is a reference to a scalar that will be used as the key).</p>

<p>Note that all &#39;keys&#39; that work for arrays also work for hashes. If you have a reference that is overloaded such that it can both act as an array reference and as a hash reference [or, in the case of DiveVal() and DiveRef(), if you have an undefined <code>$ref</code> which can be autovivified into either type of reference], then numeric-looking key values cause an array dereference. In the above cases, if you want to do a hash dereference, then you need to pass in a reference to the key.</p>

<p>Note that undefined keys are reserved for a special meaning discussed in <a href="./Data::Diver.html#Advanced-&#39;key&#39;-values">&quot;Advanced &#39;key&#39; values&quot;</a> further down. That section discusses how to dereference other types of references [scalar references and subroutine references] and exactly how the different reference types and key values interact.</p>

<h2 id="DiveError">DiveError</h2>

<pre><code>    ( $errDesc, $ref, $svKey )= DiveError();</code></pre>

<p>In the case of Dive() returning an empty list, a subsequent call to DiveError() will return a description of why Dive() failed, the specific reference that was trying to be dereferenced [not just the top-level $root reference that was passed into Dive], and a reference to the specific &#39;key&#39;.</p>

<h2 id="DiveClear">DiveClear</h2>

<pre><code>    DiveClear();</code></pre>

<p>DiveClear() erases the record of any previous Dive() failures.</p>

<h2 id="DiveDie">DiveDie</h2>

<pre><code>    DiveDie();</code></pre>

<p>or</p>

<pre><code>    $value= DiveDie( Dive(...) );</code></pre>

<p>or</p>

<pre><code>    $value= DiveDie( $root, @ListOfKeys );</code></pre>

<p>This <code>die</code>s with an error message based on the previously saved Dive() failure reason.</p>

<p>If there is no previously saved failure reason or if one argument is passed into DiveDie(), then it simply returns that argument [or an empty list].</p>

<p>If more than one argument is passed into DiveDie(), then those arguments are passed to Dive() and then DiveDie() behaves as described above. That is, <code>DiveDie($root,@list)</code> acts the same as <code>DiveDie(Dive($root,@list))</code>.</p>

<h2 id="Advanced-&#39;key&#39;-values"><a id="Advanced"></a><a id="Advanced--key--values"></a>Advanced &#39;key&#39; values</h2>

<p>For both Dive() and DiveRef(), each $key in @ListOfKeys can have the following values:</p>

<dl>

<dt id="undef"><code>undef</code></dt>
<dd>

<p>This means that you expect <code>$ref</code> to be a reference to a scalar and you want to dereference it.</p>

<p>For Dive(), if <code>$ref</code> is undefined or is something that can&#39;t act as a reference to a scalar, then the empty list is returned and DiveError() can tell you where the problem was.</p>

<p>For DiveRef(), if <code>$ref</code> is <code>undef</code>, then it will be autovivified into a reference to a scalar [that will start out undefined but may quickly become autovivified due to the next element of @ListOfKeys]. If <code>$ref</code> is something that can&#39;t act as a scalar reference, then Perl will <code>die</code> to tell you why.</p>

<p>Otherwise the scalar ref is deferenced (<code>$$ref</code>) and we continue on to the next element of @ListOfKeys.</p>

</dd>
<dt id="a-reference-to-a-scalar"><a id="a"></a>a reference to a scalar</dt>
<dd>

<p>This means that you expect <code>$ref</code> to be a reference to a hash and you want to dereference it using <code>$$key</code> as the key.</p>

<p>This is most useful for when you want to use hash keys that match <code>m/^-?\d+$/</code>. Note that <code>\( listOfScalars )</code> will give you a list of references to those scalars so you can often just add <code>\(</code> and <code>)</code> around your list of keys if you only want to do hash dereferencing:</p>

<pre><code>    DiveVal( $ref, \( 1, -5, qw&lt; 00 01 &gt;, list(), 1-9, 0xFF ) )= 9;</code></pre>

<p>But, if your argument list of key values is build out of at least one array and any other item, then it won&#39;t work since:</p>

<pre><code>    \( @a, $b, 9 ) is ( \@a, \$b, \9 )</code></pre>

<p>so you&#39;ll need to either wrap each array in additional parens or use <code>map</code>:</p>

<pre><code>    \( (@a), $b, (@c), 9 )

    map \$_, @a, $b, @c, 9</code></pre>

</dd>
<dt id="$key-=~-m/^-?\d+$/"><a id="key---m---d"></a><code>$key =~ m/^-?\d+$/</code></dt>
<dd>

<p>This means that you might expect <code>$ref</code> to be a reference to an array.</p>

<p>For Dive(), if <code>$ref</code> can act as a reference to an array and $key is in range ( -@$ref &lt;= $key and $key &lt;= $#$ref ), then <code>$ref= $ref-&gt;[$key];</code> is run [and this can&#39;t fail nor autovivify since we&#39;ve already checked how big that array was].</p>

<p>If $ref can&#39;t be used as an array reference, then $ref might be used as a hash reference instead, as described further down.</p>

<p>If $ref is undefined or $key is out of range ($key &lt; -@$ref or $#$ref &lt; $key), then Dive() returns an empty list.</p>

<p>For DiveRef(), if <code>$ref</code> is undefined, then it is autovivified into a reference to anonymous array. If <code>$ref</code> can act as a reference to an array, then <code>$ref= $ref-&gt;[$key]</code> is attempted. If $key is larger than $#$ref, then @$ref will grow. If $key is less than -@$ref, then Perl will <code>die</code>.</p>

<p>If <code>$ref</code> cannot act as a reference to an array, then $ref might be used as a reference to a hash as described further down.</p>

</dd>
<dt id="a-reference-to-an-array"><a id="a1"></a>a reference to an array</dt>
<dd>

<p>If $key can be used as a reference to an array, then it means that you might expect <code>$ref</code> to be a reference to a subroutine.</p>

<p>If <code>UNIVERSAL::isa( $ref, &#39;CODE&#39; )</code> is true, then <code>$ref-&gt;( @$key )</code> is attempted.</p>

<p>If $key isn&#39;t the last value in @ListOfKeys and the next value is undefined, then &amp;$ref is called in a scalar context and $ref is set to refer to the scalar value returned.</p>

<p>Otherwise, &amp;$ref is called in a list context and $ref is set to refer to an anonymous array containing the value(s) returned.</p>

</dd>
<dt id="any-(defined)-string"><a id="any"></a><a id="any--defined--string"></a>any (defined) string</dt>
<dd>

<p>This means that you might expect <code>$ref</code> to be a reference to a hash.</p>

<p>For Dive(), if <code>$ref</code> can act as a reference to a hash and <code>&lt;exists $ref-</code>{$key} &gt;&gt; is true, then <code>$ref= $ref-&gt;{$key};</code> is run [and this can&#39;t fail nor autovivify].</p>

<p>Otherwise, Dive() returns an empty list and DiveError() can tell you where the problem was.</p>

<p>For DiveRef(), <code>$ref= $ref-&gt;{$key}</code> is simply attempted. This may autovivify a hash entry or even a new hash. It may also <code>die</code>, for example, if $ref can&#39;t be used as a hash reference.</p>

</dd>
</dl>

<p>Note that the order of the above items is significant. It represents the order in which cases are tested. So an undefined $key will only be for derefencing a scalar reference and a numeric key will prefer to treat a reference as an array reference.</p>

<h1 id="AUTHOR">AUTHOR</h1>

<p>Tye McQueen, http://www.perlmonks.org/?node=tye</p>

<h1 id="SEE-ALSO"><a id="SEE"></a>SEE ALSO</h1>

<p>Once More With Feeling -- Joss++</p></div>

<div id="metacpan_install-instructions-dialog" class="modal fade">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
        <h4 class="modal-title">Module Install Instructions</h4>
      </div>
      <div class="modal-body">
        <p>To install Data::Diver, copy and paste the appropriate command in to your terminal.</p>
        <p><a href="https://metacpan.org/dist/App-cpanminus/view/bin/cpanm">cpanm</a></p>
        <pre><code>cpanm Data::Diver</code></pre>
        <p><a href="https://metacpan.org/pod/CPAN">CPAN shell</a></p>
        <pre><code>perl -MCPAN -e shell
install Data::Diver</code></pre>
        <p>For more information on module installation, please visit <a href="https://www.cpan.org/modules/INSTALL.html">the detailed CPAN module installation guide</a>.</p>
      </div>
      <div class="modal-footer">
        <a href="./Data::Diver.html#" data-dismiss="modal" class="btn">Close</a>
      </div>
    </div>
  </div>
</div>
          </main>
          <div class="content-pagination">
          </div>
        </div>
        <footer class="footer">
          <div class="footer-container">
            <div class="footer-social">
              <div class="footer-link footer-logo">
                <a href="https://metacpan.org/">
                  <img src="https://metacpan.org/static/images/metacpan-logo.svg" alt="MetaCPAN" />
                </a>
              </div>
              <a class="footer-social-link" href="https://github.com/metacpan">
                <i class="fab fa-github-square"></i>
              </a>
              <a class="footer-social-link" href="https://fosstodon.org/@metacpan">
                <i class="fab fa-mastodon"></i>
              </a>
            </div>
            <div class="footer-links">
              <div class="footer-link">
                  <a href="https://metacpan.org/about">About</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/sponsors">Sponsor</a>
              </div>
              <div class="footer-link">
                  <a href="https://grep.metacpan.org">grep::cpan</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/recent">Recent</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/faq">FAQ</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/tools">Tools</a>
              </div>
              <div class="footer-link">
                  <a href="https://fastapi.metacpan.org/">API</a>
              </div>
              <div class="footer-link">
                  <a href="https://www.perl.org/">Perl.org</a>
              </div>
            </div>
            <div class="footer-sponsors">
              <a class="footer-sponsor-link" target="_blank" href="https://www.bytemark.co.uk/" rel="noopener">
                <img class="footer-sponsor-bytemark" src="https://metacpan.org/static/images/sponsors/bytemark_logo.svg" alt="Bytemark logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.liquidweb.com/" rel="noopener">
                <img class="footer-sponsor-liquidweb" src="https://metacpan.org/static/images/sponsors/liquidweb_logo.png" alt="liquidweb logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://deriv.com/careers/" rel="noopener">
                <img class="footer-sponsor-deriv" src="https://metacpan.org/static/images/sponsors/deriv.svg" alt="Deriv logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://geocode.xyz" rel="noopener">
                <img class="footer-sponsor-geocode" src="https://metacpan.org/static/images/sponsors/geocodelogo.svg" alt="Geocode logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.fastly.com/" rel="noopener">
                <img class="footer-sponsor-fastly" src="https://metacpan.org/static/images/sponsors/fastly_logo.svg" alt="Fastly logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://opencagedata.com" rel="noopener">
                <img class="footer-sponsor-opencage" src="https://metacpan.org/static/images/sponsors/open-cage.svg" alt="OpenCage logo">
              </a>
            </div>
          </div>
        </footer>
        <div class="modal fade" tabindex="-1" role="dialog" id="metacpan_keyboard-shortcuts">
          <div class="modal-dialog">
            <div class="modal-content">
              <div class="modal-header">
                <button type="button" class="close" data-dismiss="modal">&times;</button>
                <h4 class="modal-title">Keyboard Shortcuts</h4>
              </div>
              <div class="modal-body row">
<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Global</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>s</kbd>
        </td>
        <td>Focus search bar</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>?</kbd>
        </td>
        <td>Bring up this help dialog</td>
      </tr>
    </tbody>
  </table>

  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>GitHub</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>p</kbd>
        </td>
        <td>Go to pull requests</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>go to github issues (only if github is preferred repository)</td>
      </tr>
    </tbody>
  </table>
</div>

<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>POD</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>a</kbd>
        </td>
        <td>Go to author</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>c</kbd>
        </td>
        <td>Go to changes</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>Go to issues</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>d</kbd>
        </td>
        <td>Go to dist</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>r</kbd>
        </td>
        <td>Go to repository/SCM</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>s</kbd>
        </td>
        <td>Go to source</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>b</kbd>
        </td>
        <td>Go to file browse</td>
      </tr>

    </tbody>
  </table>
</div>

<div class="col-md-12">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Search terms</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><em>module:</em> (e.g. <a href="https://metacpan.org/search?q=module%3APlugin">module:Plugin</a>)</td>
      </tr>
      <tr>
        <td><em>distribution:</em> (e.g. <a href="https://metacpan.org/search?q=distribution%3ADancer+auth">distribution:Dancer auth</a>)</td>
      </tr>
      <tr>
        <td><em>author:</em> (e.g. <a href="https://metacpan.org/search?q=author%3ASONGMU+Redis">author:SONGMU Redis</a>)</td>
      </tr>
      <tr>
        <td><em>version:</em> (e.g. <a href="https://metacpan.org/search?q=version%3A1.00">version:1.00</a>)</td>
      </tr>
    </tbody>
  </table>
</div>
              </div>
              <div class="modal-footer"></div>
            </div>
          </div>
        </div>
    </body>
</html>
